What

Add configurable rebalance strategy for bridge pegout, supporting two modes: ALL_AT_ONCE (existing behavior - converts entire RSK balance to BTC in a single transaction) and UTXO_SPLIT (splits the pegout amount into multiple UTXOs based on the provider's min/max pegout limits for better liquidity distribution)

Why

The current rebalance behavior sends all funds waiting for rebalance in a single native pegout transaction, causing UTXOs to converge into one during usage spikes
When all liquidity is consumed, only one large native pegout is executed, reducing UTXO availability for subsequent operations

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change
• Documentation update
• Refactoring (no functional changes, no api changes)
• Performance improvement
• Test updates
• Security fix
• Deployment/Infrastructure changes

Affected part of the project

• Management UI / API
• PegIn flow
• PegOut flow
• Utility scripts
• Configuration files
• Metrics and alerting

Related Issues

Jira ticket

How to test

Set REBALANCE_STRATEGY=UTXO_SPLIT, initiate a large pegout (e.g. 3 RBTC), wait for rebalance, and verify the LP BTC wallet receives multiple UTXOs of ~BridgeTransactionMin size instead of one large UTXO
Set REBALANCE_STRATEGY=ALL_AT_ONCE, repeat the same flow, and verify the LP BTC wallet receives a single UTXO with the full amount
Run unit tests: go test ./internal/usecases/pegout/ -run TestBridgePegout

Reviewer Guidelines

• Verify the splitting math: firstChunk + (N-1)×bridgeMin = totalValue
• Review partial failure handling — acceptable trade-off?
• Check if updateQuotes storing only last tx hash needs a follow-up ticket
• Confirm BridgeTransactionMin in management API matches the Bridge's actual minimum
• Verify the 66-tx scenario (100 RBTC test case) is acceptable for production Bridge load
• Decide if discarded error from Div() should use explicit _ or add a comment
• Test locally with REBALANCE_STRATEGY=UTXO_SPLIT in .env.regtest and run pegout-cycle.sh full-cycle --repeat 3 + check-btc-release

Screenshots (if applicable)

Add screenshots or GIFs to help explain your changes.

Additional Notes

AI Code Review: Configurable Rebalance Strategy for Bridge Pegout

Commit: 5cea8c2 — "Add configurable rebalance strategy for bridge pegout"
Branch: feature/FLY-2235
Reviewer: Claude Opus 4.6 (AI-assisted review)
Date: 2026-03-13

1. Summary

This feature introduces a configurable rebalance strategy for the bridge pegout flow. Previously, the LP always sent the entire accumulated refund total to the RSK Bridge in a single transaction (ALL_AT_ONCE). The new UTXO_SPLIT strategy splits the bridge conversion into multiple transactions of BridgeTransactionMin size each, producing multiple UTXOs on the BTC side.

Motivation: When the Bridge releases BTC back to the LP, each bridge transaction produces one UTXO. With UTXO_SPLIT, the LP receives N smaller UTXOs instead of one large one, improving UTXO management for future pegout operations.

2. Files Changed

3. Architecture & Data Flow

Environment                    Registry                       Use Case
─────────────────────────────────────────────────────────────────────────
REBALANCE_STRATEGY env var
        │
        ▼
PegoutEnv.RebalanceStrategy
  (validated: required,
   oneof=ALL_AT_ONCE
         UTXO_SPLIT)
        │
        ▼
                         ParseRebalanceStrategy()
                               │
                               ▼
                         NewBridgePegoutUseCase(..., strategy)
                               │
                               ▼
                         BridgePegoutUseCase.strategy (immutable field)
                               │
                               ▼
              ┌────────────────┴────────────────┐
              │                                 │
        ALL_AT_ONCE                       UTXO_SPLIT
              │                                 │
              ▼                                 ▼
     runAllAtOnce()                    runUtxoSplit()
     1 × SendRbtc(total)              N × SendRbtc(bridgeMin)
                                       (first chunk = bridgeMin + remainder)

Trigger Path

1. PegoutBridgeWatcher ticks every 5 minutes
2. Queries quotes in RefundPegOutSucceeded state
3. Calls BridgePegoutUseCase.Run(ctx, quotes...)
4. Run() calculates totalValue = Σ(Value + CallFee + GasFee) for all quotes
5. If totalValue < BridgeTransactionMin → skip (normal, logged as info)
6. Acquires rskWalletMutex
7. Delegates to runAllAtOnce() or runUtxoSplit() based on strategy

4. Splitting Algorithm (UTXO_SPLIT)

Input:  totalValue, bridgeMin (from PegoutConfiguration)

numTxs    = totalValue / bridgeMin          (integer division, truncated)
remainder = totalValue - (numTxs × bridgeMin)

Invariant: numTxs × bridgeMin + remainder = totalValue (exact, no rounding)

If N = 1:
    Send 1 tx of totalValue (no split needed)

If N ≥ 2:
    Tx 1:     bridgeMin + remainder    (first chunk absorbs the remainder)
    Tx 2..N:  bridgeMin each

Sum = (bridgeMin + remainder) + (N-1) × bridgeMin
    = N × bridgeMin + remainder
    = totalValue                       ✓ exact

Why this is rounding-safe: All arithmetic uses Go's math/big.Int (arbitrary precision integers). The remainder is computed by subtraction (total - N×min) rather than modulo, so firstChunk + (N-1)×min = total is an algebraic identity, not an approximation.

Gas Calculation

gasPerTx        = BridgeConversionGasLimit × BridgeConversionGasPrice = 100000 × 60000000 = 6×10¹² wei
requiredBalance = totalValue + N × gasPerTx

For ALL_AT_ONCE, gas is 1 × gasPerTx. For UTXO_SPLIT with N transactions, gas scales linearly as N × gasPerTx.

5. Code Review Findings

5.1 Correctness

5.2 Error Handling

5.3 Design Observations for Peer Discussion

A. Partial Success Handling in UTXO_SPLIT

When N≥2 and tx K fails (K>1), transactions 1..K-1 have already been sent to the bridge and cannot be rolled back. The code marks all quotes as BridgeTxFailed:

// bridge_pegout.go:177-185
for i := uint64(1); i < n; i++ {
    config = blockchain.NewTransactionConfig(bridgeMin.Copy(), ...)
    receipt, txErr = useCase.rskWallet.SendRbtc(ctx, config, bridgeAddress)
    if txErr == nil {
        log.Debugf(...)
    } else {
        break
    }
}
err = useCase.updateQuotes(ctx, receipt, txErr, watchedQuotes)

What happens:

• RBTC from successful txs has already been sent to the Bridge — those funds are in transit and will eventually produce BTC UTXOs
• But all quotes are marked BridgeTxFailed, so the watcher won't re-process them
• The Bridge will still release BTC for the successful txs (bridge is stateless w.r.t. LPS quote tracking)

Assessment: This is a conservative design choice — it prevents double-sending by marking all quotes as terminal. The LP receives the partial BTC but the accounting is pessimistic. An operator would need to reconcile manually.

Alternative (not necessarily better): Track per-tx success and mark quotes proportionally. But this adds complexity and partial state management that may not be worth it given the rarity of mid-split failures.

B. updateQuotes Uses Last Receipt Only

In the split loop, updateQuotes is called once with the final receipt:

// bridge_pegout.go:187
err = useCase.updateQuotes(ctx, receipt, txErr, watchedQuotes)

On success (all N txs complete), receipt is from the last tx. This means BridgeRefundTxHash on all quotes points to tx N, not tx 1. For ALL_AT_ONCE this is fine (one tx). For UTXO_SPLIT, it means quote records reference only the last bridge tx hash.

Impact: The other tx hashes are logged (debug level) but not persisted in the database. If an operator needs to audit all bridge transactions for a rebalance cycle, they'd need to check logs or chain state.

C. numTxs Returned as *Wei From Division

numTxs, _ := new(entities.Wei).Div(totalValue, bridgeMin)

The error from Div is discarded. This is safe because bridgeMin is validated upstream (it passes the BridgeTransactionMin.Cmp(totalValue) > 0 check at line 79, confirming bridgeMin > 0), so division by zero cannot occur. However, the discarded error is a minor code smell.

D. Default Strategy is ALL_AT_ONCE

The switch statement defaults to runAllAtOnce:

switch useCase.strategy {
case UtxoSplit:
    return useCase.runUtxoSplit(...)
default:
    return useCase.runAllAtOnce(...)
}

This is safe: even if a new strategy value were somehow injected, the system falls back to the original single-tx behavior. The double validation (env + parsing) prevents this in practice.

6. Test Coverage Assessment

Existing Tests (from the cherry-picked commit)

Added Tests (on this branch)

Cases in the integrity test:

Coverage Gaps (Minor)

1. No test with multiple quotes and UTXO_SPLIT — all UTXO_SPLIT tests use a single quote or the shared bridgePegoutTestWatchedQuotes. A test with many quotes where Value+CallFee+GasFee produces an interesting total would add confidence.
2. No test for first tx failure in N≥2 — testUtxoSplitFailMidSplit tests tx2 failure. A test where tx1 itself fails would verify the early-exit path at lines 170-175.

7. Security Assessment

7.1 LPS Flow Security

7.2 Rootstock Federation Bridge Flow Security

This section examines how the UTXO_SPLIT strategy affects the RSK Bridge and federation nodes.

Bridge Perspective

The RSK Bridge at 0x0000000000000000000000000000000001000006 processes incoming RBTC transfers as pegout requests. Each transfer that meets the minimum lock value is queued for BTC release.

BTC Side

Timing & Ordering

7.3 Attack Scenarios Considered

7.4 Security Verdict

No security vulnerabilities identified. The feature is a clean extension of the existing rebalance flow. The UTXO_SPLIT strategy interacts with the Bridge in the same way as ALL_AT_ONCE — it simply sends multiple qualifying transfers instead of one. The Bridge's native handling of pegout queues, fee calculation, and federation signing is unaffected.

The one operational risk (partial failure accounting mismatch) is a design trade-off, not a vulnerability. It favors safety (no double-send) over convenience (manual reconciliation).

8. Compatibility with This Branch

The main feature commit was tested on master and then moved onto feature/FLY-2235. Key differences on this branch:

All unit tests pass on the branch (32 packages). Build compiles cleanly. No merge conflicts.